Shareware Grab Bag/Shareware Grab Bag.iso/007/d86.arc/MAIN.DOC

Text File | 1986-08-29 | 10.5 KB | 230 lines

---MAIN.DOC---

Invoking the D86 Debugger

D86 is the screen-oriented symbolic debugger used with programs assembled
under the assembler A86.   D86 runs on an MS-DOS system, with an IBM-compatible
monochrome or color-graphics video interface.

You invoke D86 by issuing the command

   D86 [-V] [progname [command-tail]]

where progname.SYM and progname.COM are the symbols and output files of the A86
assembler.  In other words, you simply provide the program invocation line,
with the word D86 appended to the start.

It is not necessary for progname.SYM to be present.  If it is not, then the
debugger simply comes up with no user symbols defined.

You can also invoke D86 with no progname.  The debugger comes up with no
program loaded, allowing you to simply poke around the machine.

If you don't see symbols, or you don't see your program in memory, then D86
had some problem loading your files.  The later, product-quality version of
D86 will tell you this explicitly, but right now you simply have to deduce it.

The -V option can be used if you have both a monochrome and a color monitor.
If you specify -V, the debugger will appear on whichever screen is NOT currently
selected.  This allows you to see both the debugger output and the program
output at the same time.


The D86 Screen Display

When D86 starts up, it generates a full-screen display, and awaits your
debugger commands.

In the top part of the screen is a symbolic disassembly of the A86 program,
with the screen cursor positioned next to the instruction pointed to by the
8086 instruction pointer.

In the lower right corner is a fixed display of the complete 8086 register set.

At the top of the second column of the register-set display is a display of the
8086 flags.  Each flag displays as blank if the flags is off; and a lower-case
letter if the flag is on:
          "o" for overflow,
          "d" for direction,
          "i" for interrupts enabled,
          "s" for sign,
          "z" for zero,
          "a" for auxiliary carry,
          "p" for parity even, and
          "c" for carry.

Across the bottom line of the screen is a display of the contents of the user
stack.  The display begins next to the SP register value, with the number of
elements on the stack.  (The stack is assumed to have 0 elements when SP is at
its original value, 0FFFE). The number of elements is followed by a colon,
followed by as many of the top stack elements as fits on the line.  The
initial display will have zero elements; nothing is yet on the stack.

To the right of the registers are 6 lines, numbered 1 through 6.  On these
lines, you can generate windows into 8086 memory, displaying bytes, words,
or ASCII text in a variety of formats. The windows can be located either at
absolute memory locations, or be pointed to by any of the 8086 registers.  The
commands you issue to generate these windows are described in the next section.



D86 Commands

There are 5 kinds of activities you perform in D86:

   1. Issuing assembly-language commands for immediate execution
   2. Issuing debugger commands via lines that begin with a single letter
   3. Issuing debugger commands via the function and edit keys on your keyboard
   4. Setting up windows displaying memory
   5. Issuing assembly-language commands to enter into memory (PatchMem)



Immediate Assembly-Language Commands

A primary part of the D86 command language is the A86 assembly language. With
it, you can jump to different areas of your program, set your registers,
perform arithmetic, and call any of the procedures of your program.  Simply
type in any legal A86 instruction, and it will be executed immediately.

JMP and RET instructions cause the program counter (and thus also the
disassembly) to move to the indicated destination.  CALL instructions cause
the entire procedure to be executed.

WARNING: The immediate-execution feature is a little tricky if you are in
  a multi-segment program, of if you jump to exotic parts of the 86 memory
  space (i.e., into MSDOS, ROM, video memory, or the interrupts table).
  This is because D86 needs a buffer in which to put the immediate-execution
  command.  The buffer should be in your program's CS segment, so that commands
  such as jumps and near calls execute correctly.  So D86 must always search
  in CS for a satisfoactory buffer.  Here is how D86 finds it:

  1. If you declare a label D86_BUFFER, pointing to a buffer within your
     program, then D86 will use that buffer as the offset for its immediate
     instruction.

  2. If not, then if the program's CS register is the same as its SS register,
     D86 will use (SP-300) as its immediate buffer.  Thus, our stack should
     have plenty of room (a good practice in general).

  3. As a last resort, D86 uses offset 00E0, which points to the last 32 bytes
     of the Program Segment Prefix (PSP).  In that case, if you were to issue
     an immediate command that read from a disk file, you would be in trouble,
     because the disk-read operation clobbers the PSP, and the command would
     then not be trapped back to the debugger.

  In cases 1 and 3 above, the segment containing the buffer is the program's
  CS segment, unless that is out of range (below the program's original CS,
  or above the top of available program memory).  If the program CS is out of
  range, the program's original CS is used instead.  In that case, immediate
  instructions such JMP, RET, and CALL will not work correctly.

  Note that the above caveats to not apply to single-stepping.



Entering Instructions Into Memory

D86 allows you to alter 8086 memory in two ways: first, you can issue
immediate assembly language commands which, when executed, store values in
memory.  The other method is to enter a special mode, in which you enter
instructions directly into 8086 memory.

You enter this mode by typing the F7 (PatchMem) key. The screen cursor jumps
from the left edge of the line at the current program counter, into the middle
of the line where the instruction is.  You start typing over the instruction,
to signal that you are clobbering the instruction that was there.  If you did
not intend to enter this mode, you can backspace back to the start of the
instruction, and type a carriage-return.

Each line you type in is checked for errors.  If there was an error, a message
is displayed, the cursor remains at the same location, and you try again.
If there was no error, the cursor moves beyond the newly-assembled line, and
you can type in another line.

To exit the memory-programming mode, you type any of the control-key commands
at the beginning of the line.  (Type carriage-return if you don't want any
actions to be performed.)


Entering Data into 8086 Memory

You can deposit data into the 8086 memory space by using the programming mode
described in the above section.  Simply enter DB and/or DW statements instead
of instructions.  Note that ASCII strings can be entered with the DB
instruction; and that arrays can be initialized via the DUP operator in a DB
or DW statement.


Adding Symbols to a Program

Patch-mode also allows you to do something that you cannot do in immediate-
execution mode: add symbols to the program.  You can do so by either:

   1. Typing in a new symbol-name, followed by a colon; or
   2. Typing in an EQU directive.

There are several uses for this.  First, you might want to create an
abbreviation, by equating a short name to a long one, or to a hard-to-remember
constant value.  Second, you might want to "reverse engineer" a program for
which you have a .COM file, but not the A86 source code.  Each time you add a
label, the disassembly becomes more readable.  Third, you might want to label
code which you have added in patch-mode.

Starting with V2.16, forward referencing is now allowed when you are in patch
mode.  You must be careful, however, to reslove any forward references you have
made.  In particular, you will cause the assembler to become very confused (and
possibly trash random memory) if you overwrite a forward reference with some
other code before you resolve the reference.  So don't!


D86 Control-Key Functions

D86 has a set of functions invoked by single keys, which can be invoked any
time D86 is awaiting the beginning of an assembly-language command.

F1           Single-step the current instruction.  If the instruction is a call,
             go into the procedure to single-step it.  If you want the entire
             procedure executed on a single keystroke, use the F2 key.

F2           Procedure-step: start program, trapping at the instruction
             following the current one.  This is used for executing a procedure
             call all at once; for breaking out of a loop; and for executing
             a repeated string operation all at once.

F3           Repeat the last typed-in assembly language or debugger command

F4           Start the program, setting a trap at the destination of the
             conditional-jump instruction currently pointed to.  If we are not
             pointing to a conditional jump, then we single-step.

F6           Start the program, setting a trap at the address on top of the
             stack (hopefully a procedure-return address).

F7           Enter the previously-described Patch Memory mode.

Alt-F9       If you have a Color video board, your debugger display may become
             corrupted by the program's console output.  If it does, press
             Alt-F9 to eliminate the corruption.  This key exists only
             temporarily; on later versions of D86, the corruption will be
             corrected automatically.

F10          When you are in Help-Mode, this key gives you alternate help
             windows in some contexts.  When you are not in Help-Mode, this
             key toggles though the display windows: in this preliminary
             debugger, that is just the sign-on message and a blank window.

Down-arrow   Jump to the instruction following the current one, without
             executing the current instruction.

Up arrow     "Up": decrement the current program counter.

Pg Dn        Jump to the next disassembly page, without executing.

Home         Jump to location 0100 in the current code segment.  In most
             .COM programs, this will be the start of the program.  NOTE that
             no other re-initializations take place with this command.  If you
             wish to completely reinitialize your program, you should exit
             and reenter the debugger.